repeat

Type

control structure

Summary

Executes a set of statements repeatedly.

Syntax

repeat [{forever | while <condition> | until <condition>}]
    <statementList>
end repeat

repeat [for] <number> [times]
    <statementList>
end repeat

repeat with <counterVariable> = <startValue> {to | down to} <endValue> [step <increment>]
    <statementList>
end repeat

repeat for each <chunkType> <labelVariable> in <container>
    <statementList>
end repeat

repeat for each {element | key} <labelVariable> in <array>
    <statementList>
end repeat

Description

Use the repeat control structure to perform the same series of actions for each member of a set: for example, for each card in a stack, or each line in a variable.

####Loop Form: The loop form is one of the following forms:

• forever
• until condition
• while condition
• [for] number [times]
• with counterVariable=startValue` {to | down to}

    `*`endValue`*` [step `*`increment`*`]`
  - `for each `*`chunkType`* *`labelVariable`*` in `*`container`*
  - `for each element `*`labelVariable`*` in `*`array`*
  - `for each key `*`labelVariable`*` in `*`array`*

The repeat control structure always begins with the repeat keyword. The last line of a repeat control structure is always the end repeat keyword.

How many times the statementList is executed depends on the loop form you use. Here are details of the possible forms:

#####Forever The forever form continues repeating the statements in the statementList until an exit, exit repeat, pass, or return statement is executed. Usually, one of these control structure|control structures is included in an if control structure within the statementList.

Use the forever form if you want to test a condition at the bottom of the loop, after the statementList is executed. In the following example, the go command is executed at least once, since the mouseClick is not checked until after the go command:

    repeat forever
        go next card
        if the mouseClick then exit repeat -- user clicked
    end repeat

If no loopForm is specified, the forever form is used.

#####Until and while The until condition and while condition forms repeat the statementList as long as the condition is false or as long as it is true, respectively. LiveCode re-evaluates the condition before each iteration.

Use the until condition or while condition form if you want to test a condition at the top of the loop, before the statements are executed. This example scrolls through the cards until the user clicks the mouse:

    repeat until the mouseClick
        go next card
        wait for 100 milliseconds
    end repeat

This example repeats as long as the total number of characters in a field is less than the given amount:

    local tCount
    put empty into field \"myField\"
    put 20 into tCount
    repeat while the number of characters in field \"myField\" < tCount
        put \"X\" after field \"myField\"
    end repeat

#####[For] number [times] The for number times form repeats the statementList for the specified number of times. The number is evaluated when the loop is first entered, and is not re-evaluated as a result of any actions performed in the statementList. For example, if the number is the number of cards, and the statementList contains a create card command, the loop is executed as many times as there were cards when the loop began, even though the current number of cards is changing with each iteration through the loop.

If the number is not an integer, it is rounded to the nearest integer, using the same rules as the round function. Use the for number times form if you want to execute the statementList a fixed number of times. The following simple example beeps three times:

    repeat for 3 times
        beep
    end repeat

Note that for and times are optional. For example the following is also valid:

    repeat 3
        beep
    end repeat

#####With counterVariable The with counter=startValuetoendValue form and the with counter=startValuedown toendValue form set the counter to the startValue at the beginning of the loop, and increase (or decrease, if you're using the down to form) the countVariable by 1 each time through the loop. When the counter is greater than or equal to the endValue, (less than or equal to, if you're using the down to form), the loop performs its final iteration and then ends.

If you specify an increment, the increment is added to the counter each time through the loop, rather than the counter being increased by 1. (The increment is not treated as an absolute value: if you're using the down to form, the increment must be negative.)

As with the for number times form described above, the startValue and endValue are evaluated when the loop is first entered, and are not re-evaluated as a result of any actions performed in the statementList.

Use one of these forms if you want to perform an action on each member of a set, and you need to refer to the member by number within the statementList. The following example loops through all the controls on the current card. The counterVariable x is 1 during the first iteration, 2 during the second, and so on:

    repeat with x = 1 to the number of controls
        show control x
    end repeat

The following example loops backwards through a set of lines. The counterVariable myLine is 20 during the first iteration, 18 during the second, and so on:

    repeat with myLine = 20 down to 1 step -2
        put myLine
    end repeat

note

The counterVariable myLine is 0 in the final iteration of the loop as it is only once the counterVariable is less than or equal to the endValue that the loop will perform its final iteration. To prevent the loop executing one more iteration than desired, one could compare the two and use exit repeat to end the iteration immediately. For example:

    repeat with myLine = 20 to 1 step -2
        if myLine < = 1 then exit repeat
        put myLine
    end repeat

note

It is possible to change the counterVariable in a statement in the loop. However, doing this is not recommended, because it makes the loop logic difficult to follow:

    repeat with x = 1 to 20 -- this loop actually repeats ten times
        answer x
        add 1 to x -- not recommended
    end repeat

#####For each The for each chunkType labelVariableincontainer form sets the labelVariable to the first chunk of the specified chunkType in the container at the beginning of the loop, then sets it to the next chunk for each iteration. For example, if the chunkType is word, the labelVariable is set to the next word in the container for each iteration of the loop.

Use the for each form if you want to perform an action on each chunk in a container. This form is much faster than the with countVariable=startValuetoendValue form when looping through the chunks of a container. The following example changes a return-delimited list to a comma-delimited list:

    repeat for each line thisLine in myList
        put thisLine & comma after newList
    end repeat
    delete the last char of newList

The for each element labelVariableinarray form sets the labelVariable to the first element in the array at the beginning of the loop, then sets it to the next element for each iteration.

Use the for eachelement form if you want to perform an action on each element in an array. The following example gets only the multi-word entries in an array of phrases:

    repeat for each element thisIndexTerm in arrayOfTerms
        if the number of words in thisIndexTerm > 1 then
            put thisIndexTerm & return after multiWordTerms
        end if
    end repeat

note

In any of the for each loops, you may change the labelVariable in a statement inside the loop. However, this is not recommended because it will make the logic difficult to follow. You may modify the container variable inside a loop, but the modifications will not affect what is being iterated over.

note

The repeat control structure is implemented internally as a command and appears in the commandNames.

Parameters

Name	Type	Description
statementList		One or more LiveCode statements, and can also include if, switch, try, or repeat control structures.
condition	bool	Any expression that evaluates to true or false.
number	number	A numbers or an expressions that evaluates to a number.
startValue	number	A numbers or an expressions that evaluates to a number.
endValue	number	A numbers or an expressions that evaluates to a number.
increment	number	A numbers or an expressions that evaluates to a number.
counterVariable		A legal variable name.
labelVariable		A legal variable name.
chunkType		One of these text chunk types: byte, codeunit, codepoint, character (or char), token, trueword, word (or segment), item, sentence, paragraph or line.
container		Any existing container; e.g. a variable or a field.
array	array	Any existing container, usually a variable, that contains an array of values.

Examples

-- counter variables in repeat with loops may use 0
local tVarNum, tText
repeat with tVarNum = 0 to 5
  put tVarNum & comma after tText
end repeat
put tText
-- tText = 0,1,2,3,4,5,

-- Repeat with loops can also make use of negative numbers
local tVarNum, tText
repeat with tVarNum = 3 down to -5
  put tVarNum & comma after tText
end repeat
put tText
-- tText = 3,2,1,0,-1,-2,-3,-4,-5,

-- Put a given number of X's at the end of a field
local tCount
put 5 into tCount
repeat tCount times
  put "X" after field "counting"
end repeat

Related

function: round

glossary: iteration, array, chunk, conditional, container, control structure, delimit, element, execute, field, function, integer, keyword, statement, value, variable

keyword: card, each, element, end repeat, for, forever, line, until, while

object: stack

command: wait

control structure: next repeat, exit repeat

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile